fix(responses): classify Codex WS failures instead of restating them - #4232

Summary

A long Codex thread that dies on the WebSocket transport reports one of two sentences, and neither distinguishes the cases it is true of:

codex websocket closed before a Responses terminal event (close 1006 Connection ended)
codex websocket response prelude timed out

A socket that was never answered, a socket that answered in 40 ms with a quota frame and then produced nothing for 90 seconds, and a socket that died after the response was already flowing all reach the user as the same text. The reporter of #4191 established the little that was knowable by toggling the proxy by hand and observing that the same thread recovers immediately when OpenCodex is bypassed. Making that failure legible is what this change does.

The exchange now keeps a content-free stage record: the response.create frame's byte count, whether the send completed, how many upstream frames arrived, how many of those the metadata channel claimed as quota or response metadata, how many Responses events were relayed downstream, and the durations from send to the first upstream frame and to the failure. classifyCodexWsFailure reduces that to one of before-send, no-upstream-frame, no-response-event, after-response-started, and the detail is appended to the existing message:

codex websocket closed before a Responses terminal event (close 1006 Connection ended) [cause=no-response-event request=15982104B sent=yes frames=3 control=3 relayed=0 first-frame=41ms elapsed=1204ms]

The detail is a suffix, after the close-code tail, so (close 1006 Connection ended) remains one contiguous substring for every existing reader and assertion. The frame is measured only while a failure message is being built, so the happy path never pays for sizing a multi-megabyte string. Three paths carry it: the prelude timeout, the close-before-terminal message, and the transport error. The size- and queue-limit failures already name their own precise cause and are untouched.

Every field is a size, a count, or a duration. No request body, header, close reason beyond what was already surfaced, or account identifier can reach a message built from this record.

A finding worth recording separately. Reading the exchange for this issue shows where the 90-second prelude budget actually goes: preludeTimer is armed once after a successful send and is cleared only by commitResponse(), which runs solely on a frame the metadata channel did not claim. So the budget measures send to the first Responses event, and upstream liveness on the control channel does not extend it. A socket that keeps sending quota updates while the backend works through a large replayed thread still dies at exactly 90 s, and before this change it reported the same sentence as a socket that was never answered. cause=no-response-event with control=3 first-frame=41ms is what that now looks like.

Deliberately not implemented, per the lane packet, which scopes this issue to honest classification and returns the rest as a report:

• Automatic HTTP/SSE fallback after an open socket dies. failStream treats a completed send as possibly executing upstream. The maintainer comment on the issue is explicit that responseCommitted === false and zero downstream bytes are not proof the upstream did not accept or execute the frame, so a resend gated on either can duplicate a turn. The new classification must not be read as a fallback-eligibility signal; the type comment says so at the definition, because no-upstream-frame is exactly the value a future reader would be tempted to misuse.
• A configurable or longer prelude budget (Make the Codex WebSocket response prelude timeout configurable #3976). 90 s is already three times the original 30 s, and the finding above suggests the real question is different: whether control-channel liveness should extend the budget at all.
• A size preflight below the current ceiling. codexWsCreateFrameExceedsLimit routes at 16 MiB − 64 KiB; the band just under it still dials the socket, and a long full-replay thread sits there. Narrowing eligibility by predicted size or expected time-to-first-token changes transport selection for every user, not only failing ones. The byte count now in the failure message is what would supply the measurements for that decision.

Design notes and the reproduction reasoning are in devlog/_plan/260911_l6_streaming_tools/010_4191_ws_failure_classification.md.

Refs #4191 — the report's remaining asks are answered above rather than patched, so the issue stays open.

Verification

• bun run test, bun run test:changed, bun run typecheck and bun run build:gui: NOT RUN, by operator instruction for this dispatch round. Hosted CI on the exact pushed head is the only product evidence this change offers.
• New focused regression test: tests/responses/ws-failure-stage.test.ts, in the responses domain beside ws-upstream.test.ts, registered in scripts/test-layout/layout.json and tests/fixtures/test-layout-expected.json. It covers the classifier's four stages, the renderer's exact output including the n/a durations, the contiguity of the close-code tail that existing assertions depend on, and four end-to-end cases through a fake socket: an unanswered close, a quota-only close, a close after relayed events, and the prelude timeout under fake timers.
• Compatibility with the four existing assertions in tests/responses/ws-upstream.test.ts (lines 1061, 1281, 1542-1543, 1556) was checked by reading each one: all four match on substrings or unanchored regexes that end at or before the close-code tail, and the detail is appended after it.
• Reviewed by a read-only subagent against the staged diff before push.

Checklist

• Scope stays focused and avoids unrelated cleanup.
• Docs or release notes were updated when needed.
• Security-sensitive changes were reviewed for secrets, auth, and unsafe defaults.

Summary by CodeRabbit

• Bug Fixes

  • Improved WebSocket failure reporting when a response ends unexpectedly or times out.
  • Failure messages now identify whether the issue occurred before sending, before receiving data, before a response event, or after streaming began.
  • Added diagnostic details such as request size, frame counts, relayed events, and timing to help explain incomplete responses.
  • Enhanced close and oversized-frame errors with clearer, more actionable context.

• Tests

  • Added comprehensive coverage for WebSocket failure classification, timeout handling, close messages, and streaming scenarios.